使用 MinVer 自動化 .NET 類別庫的版本號管理

TLDR

• MinVer 透過 Git Tag 自動推斷版本號，解決了 GitVersion 在升級後設定複雜且功能分支表現不穩定的問題。
• 若當前 Commit 有 Tag，則直接採用該版本；若無 Tag，則根據歷史最近的 Tag 自動遞增 Patch 或預發佈版本。
• MinVer 會自動更新 AssemblyVersion、FileVersion、PackageVersion 等屬性，簡化 CI/CD 流程。
• 建議避免使用如 0.0.1-alpha.0.0 這種結尾帶有數字的預發佈標籤，以防版本號遞增時產生混亂。
• 若執行時出現 git is not present in PATH 錯誤，請確保 Git 已正確安裝並加入系統環境變數。

MinVer 版本號運作機制

MinVer 的核心邏輯在於基於 Git 歷史紀錄進行版本推斷，適用於需要自動化管理 NuGet 套件版本的 .NET 專案。

版本推斷規則

什麼情況下會遇到版本號變動？當開發者在 Git 歷史中移動或新增標籤時，MinVer 會依據以下邏輯運作：

• 當前 Commit 擁有版本標籤：直接採用該標籤版本。
• 當前 Commit 無版本標籤：
  • 搜尋最近的標籤：
    • 若為預發佈版本：直接採用該版本並加上 height（距離標籤的 commit 數量）。
    • 若為正式版本：自動遞增 Patch 號，並加上預設的預發佈識別碼（預設為 alpha.0）與 height。
  • 若完全找不到標籤：預設使用 0.0.1-alpha.0 並加上 height。

屬性對應表

MinVer 會自動將推斷出的版本號對應至以下 .NET 組件屬性：

屬性	對應值格式
AssemblyVersion	{MinVerMajor}.0.0.0
FileVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch}.0
InformationalVersion	{MinVerVersion}
PackageVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch} (或含預發佈識別碼)

實作與設定建議

在 .csproj 檔案中，可以透過 PropertyGroup 進行客製化設定，以符合團隊的標籤命名規範。

常見設定範例

什麼情況下需要自定義設定？當團隊習慣使用 v 前綴（如 v1.0.0）或希望將預發佈識別碼改為 preview 時。

<PropertyGroup>
  <!-- 設定版本標籤前綴 -->
  <MinVerTagPrefix>v</MinVerTagPrefix>
  <!-- 自定義預發佈識別碼 -->
  <MinVerDefaultPreReleaseIdentifiers>preview.0</MinVerDefaultPreReleaseIdentifiers>
</PropertyGroup>

實作結果驗證

根據不同的 Git 狀態，MinVer 產生的版本號行為如下：

• 未標記狀態：系統會自動產生 0.0.0-alpha.0.1 格式的版本。  

• 加入正式版本標籤：若前一個 Commit 為 0.1.0，當前版本會自動遞增為 0.1.1-alpha.0.1。  

• 加入預發佈版本標籤：若前一個 Commit 為 0.0.1-alpha.0，則會基於此版本進行遞增。  

• 最新 Commit 標籤：若直接在當前 Commit 打上 0.1.2，則版本號會精確對應。  

TIP

避免使用如 0.0.1-alpha.0.0 的標籤格式，否則下一筆會變成 0.0.1-alpha.0.0.1，造成版本號混亂。

WARNING

如果專案安裝 MinVer 出現 git is not present in PATH. 錯誤，表示 Git 未設定在環境變數的 path 中。需要確保 Git 可以從命令列執行。

異動歷程

• 2025-03-29 初版文件建立。